Skip to main content
Version: 2025.10

Introduction to Istari Integrations

Istari provides a powerful integration platform that allows you to connect tools, libraries, and workflows directly into the Istari ecosystem.

Istari maintains a number of official integrations that we publish and support, but you can also create your own custom integrations. These integrations let you:

  • Connect Istari to external tools or APIs
  • Perform custom data extraction or computation
  • Run domain-specific analysis or workflows

Custom integrations in Istari are called modules. A module is essentially a package that contains one or more functions. Modules get installed onto the Istari Agent, which executes user jobs. The contract between the agent and the module is declared in a module manifest file.

How Modules Work​

When a user initiates a job in Istari, the request is executed by the Istari Agent. The Agent calls functions inside your modules by using a file-based contract.

The Agent provides your module with:

  1. Input file — path to a JSON file containing all inputs declared in your function schema
  2. Output file — path to a JSON file your function must populate with references to generated outputs
  3. Temp directory — scratch space for intermediate or working files
  4. Optional config file — JSON containing configuration values defined in the agent's istari-digital-config.yml

This design is intentionally configuration-driven and language-agnostic, giving you maximum flexibility in how you implement your functions.

Module Lifecycle​

Modules follow a simple lifecycle:

  1. Create — write the code for your function(s) using any language or SDK
  2. Scaffold — use the Istari CLI to generate a module skeleton and manifest
  3. Version — modules follow Semantic Versioning (SemVer); update the version whenever changes are made
  4. Package — bundle your function code and manifest into a distributable format (e.g., .zip or .tar)
  5. Publish — upload your module via the Istari CLI or the Agent system tray
  6. Grant access — assign permissions in the Istari management UI to make your module available to users
  7. Install on an agent — once published and access is granted, the module can be installed on an Istari Agent. Modules are installed into the Istari_modules directory inside the agent. See the Module Installation Guide for more details, as this is the same flow for both Istari native and custom modules authored with the Integrations SDK.

Module Package Layout​

A module is a self-contained directory containing your function code and a manifest file. A typical distributed module might look like this:

my_cad_integration/
├─ module_manifest.json
├─ bin/
│  └─ cad_extractor.exe
└─ lib/
   └─ helper.dll

Minimal layout requirements​

  • The manifest must always live at the root of the package
  • The rest of the directory contains your build output (executables, binaries, or libraries) needed to run your functions

You may also include source code and any supporting files inside the package. Istari does not prescribe how you organize your project — the only requirement is that your module can be invoked successfully using the run_command defined in the manifest.

Once published, the package is installed onto the Istari Agent and can be executed as part of user jobs.

Functions and Variants​

Functions inside a module are structured as objects of keyed functions. Each key corresponds to a function name, and each function can have multiple variants.

Examples of variants​

  • One variant targeting Windows, another targeting Ubuntu
  • One variant targeting SDK version 2023, another targeting SDK version 2024
  • One variant accepts XLSX files, another Sharepoint links to XLSX files

The Istari platform resolves which variant to run based on the declared operating system and tool version.

This structure gives you flexibility to maintain multiple compatible function implementations in a single module.

Scopes for Modules and Functions​

Modules and functions are identified using a scoped key syntax:

@scope:module_name
@scope:function_name
  • Istari owns the @istari scope, which denotes official first-class integrations
  • You own your own scopes and can define them for local or organizational use. For example:
    • @local:my_module for internal testing
    • @acme_corp:cad_tools for an organization-specific integration

Scopes are important for future distribution and marketplace support. Consistency is recommended, even though enforcement only applies once modules are distributed.

Best Practices​

  • Keep everything in the module — include build, install, test, and clean scripts in the manifest’s scripts section

  • Use the CLI — the Istari CLI provides commands to generate manifests, scaffold modules, run scripts, and publish integrations

  • Iterate locally first — get your function working standalone before wrapping it in a module

  • Leverage semantic versioning — publish each new version explicitly to ensure reliable distribution

  • Sign your packages and generate checksums — it is recommended that you cryptographically sign your distributed modules and generate checksums (e.g., SHA256).

    • These checksums can then be referenced in your module manifest under module_checksum to provide integrity guarantees.
    • Signing helps ensure the authenticity of your package and prevents tampering.

  • Make separate function variants for connect files and local files - If a function can process a file or a link to a file do not include these inputs in the same function variant, especially if the link requires an auth input from the agent.

Next, we'll explore how the Istari CLI supports you in authoring integrations. After that, we'll dig into the Module Manifest API Reference and walk you through how to build your first module.